# Table

## Installation

`npm i @snack-uikit/table`

[Changelog](./CHANGELOG.md)

## TODO:

- multiple row selection with Shift key pressed

## Примечание

> Для оптимальной работы таблицы используйте `useMemo` для `columnDefinitions`
> или выносите их определение за компонент

## Example

```typescript jsx
import { Table } from '@snack-uikit/table';

// ...

type TableData = {
  id: string;
  firstName: string;
  lastName: string;
  age: number;
  status: string;
}

const columnDefinitions: ColumnDefinition<TableData>[] = [
  Table.getStatusColumnDef<Person>({
    accessorKey: 'status',
    mapStatusToAppearance: {
      pending: Table.statusAppearances.Blue,
      success: Table.statusAppearances.Green,
      // ... etc
    },
    header: 'Статус',
    renderDescription: (value: string) => t(translations.statuses[value]),
    size: 250,
  }),
  {
    accessorKey: 'id',
  },
  {
    // id, size - обязательны при передаче pinned
    id: 'firstName',
    size: 140,
    pinned: 'left',
    accessorKey: 'firstName',
    header: 'Имя',
    enableSorting: true,
    sortDescFirst: true,
  },
  {
    accessorKey: 'lastName',
    header: 'Фамилия',
    cell: ctx => <div className='custom'>{ctx.getValue<string>()}</div>,
    maxSize: 200,
    enableSorting: false,
  },
  {
    accessorKey: 'age',
    header: ctx => `Можно добавить хедер так: ${ctx.column.id}`,
    minSize: 40,
  },
  Table.getRowActionsColumnDef({
    pinned: true,
    actionsGenerator: () => [
      {
        option: 'Действие с иконкой',
        icon: <PlaceholderSVG />,
        onClick: handleRowActionClick,
      },
      {
        option: 'Другое действие',
        onClick: handleRowActionClick,
      },
    ],
  })
];

// ...

<Table
  columnDefinitions={columnDefinitions}
  data={data}
  rowSelection={{
    enable: true, // false выключает выбор всех строк (состояние disabled)
    // или можно передать функцию для вычисления
    // enable: row => !['Pending', 'Loading'].includes(row.original.status),
    onChange: handleRowSelection,
  }}
/>
```

[//]: DOCUMENTATION_SECTION_START
[//]: THIS_SECTION_IS_AUTOGENERATED_PLEASE_DONT_EDIT_IT
## CopyCell
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
| value | `string \| number` | - |  |
## Table
Компонент таблицы
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
| columnDefinitions* | `ColumnDefinition<TData>[]` | - | Определение внешнего вида и функционала колонок |
| data* | `TData[]` | - | Данные для отрисовки |
| keepPinnedRows | `boolean` | - | Параметр овтечает за сохранение закрепленных строк на всех страницах таблицы |
| enableSelectPinned | `boolean` | - | Параметр овтечает за чекбокс выбора закрепленных строк |
| sorting | `{ initialState?: SortingState; state?: SortingState; onChange?(state: SortingState): void; }` | - | Параметры отвечают за возможность сортировки, их стоит использовать если нужно отслеживать состояние <br> <strong>initialState</strong>: Начальное состояние сортировки <br> <strong>state</strong>: Состояние сортировки, жестко устанавливаемое снаружи <br> <strong>onChange</strong>: Колбэк на изменение сортировки |
| rowSelection | `{ initialState?: RowSelectionState; state?: RowSelectionState; enable?: boolean \| ((row: Row<TData>) => boolean); multiRow?: boolean; onChange?(state: RowSelectionState): void; }` | - | Параметры отвечают за возможность выбора строк <br> <strong>initialState</strong>: Начальное состояние выбора строк <br> <strong>state</strong>: Состояние выбора строк, жестко устанавливаемое снаружи <br> <strong>enable</strong>: Колбэк определяющий можно ли выбрать строку <br> <strong>multiRow</strong>: Мульти-выбор строк (включен по-умолчанию, когда включается выбор) <br> <strong>onChange</strong>: Колбэк на выбор строк |
| search | `{ initialState?: string; state?: string; placeholder?: string; loading?: boolean; onChange?(value: string): void; }` | 'Search'<br> <strong>loading</strong>: Состояние загрузки в строке поиска <br> <strong>onChange</strong>: Колбэк на изменение данных в строке поиска | Параметры отвечают за глобальный поиск в таблице <br> <strong>initialState</strong>: Начальное состояние строки поиска <br> <strong>state</strong>: Состояние строки поиска, жестко устанавливаемое снаружи <br> <strong>placeholder</strong>: Placeholder строки поиска |
| enableFuzzySearch | `boolean` | - | Включить нечеткий поиск |
| pageSize | `number` | 10 | Максимальное кол-во строк на страницу |
| pagination | `{ state?: PaginationState; options?: number[]; optionsLabel?: string; onChange?(state: PaginationState): void; }` | 'Rows volume: ' <br> <strong>onChange</strong>: Колбэк на изменение пагинации | Параметры отвечают за пагинацию в таблице <br> <strong>state</strong>: Состояние строки поиска, жестко устанавливаемое снаружи <br> <strong>options</strong>: Варианты в выпадающем селекторе для установки кол-ва строк на страницу <br> <strong>optionsLabel</strong>: Текст для селектора кол-ва строк на страницу |
| pageCount | `number` | - | Кол-во страниц (используется для внешнего управления) |
| onRowClick | `RowClickHandler<TData>` | - | Колбэк клика по строке |
| className | `string` | - | CSS-класс |
| loading | `boolean` | - | Состояние загрузки |
| onRefresh | `() => void` | - | Колбек обновления данных |
| onDelete | `(selectionState: RowSelectionState, resetRowSelection: (defaultState?: boolean) => void) => void` | - | Колбек удаления выбранных |
| outline | `boolean` | - | Внешний бордер для тулбара и таблицы |
| columnFilters | `ReactNode` | - | Фильтры |
| dataFiltered | `boolean` | - |  |
| dataError | `boolean` | - |  |
| exportFileName | `string` | - | Название файла при экспорте CSV/XLSX |
| moreActions | `Action[]` | - | Элементы выпадающего списка кнопки с действиями |
| noDataState | `EmptyStateProps` | - | Экран при отстутствии данных |
| noResultsState | `EmptyStateProps` | - | Экран при отстутствии результатов поиска или фильтров |
| errorDataState | `EmptyStateProps` | - | Экран при ошибке запроса |
| suppressToolbar | `boolean` | - | Отключение тулбара |
| toolbarBefore | `ReactNode` | - | Дополнительный слот в `Toolbar` перед строкой поиска |
| toolbarAfter | `ReactNode` | - | Дополнительный слот в `Toolbar` после строки поиска |
| suppressPagination | `boolean` | - | Отключение пагинации |
| manualSorting | `boolean` | - |  |
| manualPagination | `boolean` | - |  |
| manualFiltering | `boolean` | - |  |
| getRowId | `(originalRow: TData, index: number, parent?: Row<TData>) => string` | - | Дополнительная функция используется для получения уникального идентификатора для любой заданной строки |
| scrollRef | `RefObject<HTMLElement>` | - | Ссылка на элемент, обозначающий самый конец прокручиваемого списка |
| scrollContainerRef | `RefObject<HTMLElement>` | - | Ссылка на контейнер, который скроллится |
| rowPinning | `Pick<RowPinningState, "top">` | {     top: [],   } | Определение какие строки должны быть закреплены в таблице |
## Table.getStatusColumnDef
Вспомогательная функция для создания ячейки со статусом
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
| mapStatusToAppearance* | `MapStatusToAppearanceFnType` | - | Маппинг значений статуса на цвета |
| accessorKey* | `string` | - | Имя ключа соответствующее полю в data |
| enableSorting | `boolean` | - | Включение/выключение сортировки |
| renderDescription | `(cellValue: string) => string` | - | Функция для отрисовки текста, если не передана, то будет отрисован только индикатор статуса |
| size | `number` | - | Размер ячейки |
| header | `ColumnDefTemplate<HeaderContext<TData, unknown>> & (string \| ((ctx: HeaderContext<TData, unknown>) => string))` | - | Заголовок колонки |
| enableResizing | `boolean` | - | Включение/выключение ресайза колонки |
## Table.getRowActionsColumnDef
Вспомогательная функция для создания ячейки с дополнительными действиями у строки
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
| actionsGenerator* | `ActionsGenerator<TData>` | - | Действия для строки |
| pinned | `boolean` | - | Закрепление колонки справа в таблице |
## ServerTable
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
| onChangePage* | `(offset: number, limit: number) => void` | - |  |
| columnDefinitions* | `ColumnDefinition<TData>[]` | - | Определение внешнего вида и функционала колонок |
| loading | `boolean` | - | Состояние загрузки |
| keepPinnedRows | `boolean` | - | Параметр овтечает за сохранение закрепленных строк на всех страницах таблицы |
| enableSelectPinned | `boolean` | - | Параметр овтечает за чекбокс выбора закрепленных строк |
| sorting | `{ initialState?: SortingState; state?: SortingState; onChange?(state: SortingState): void; }` | - | Параметры отвечают за возможность сортировки, их стоит использовать если нужно отслеживать состояние <br> <strong>initialState</strong>: Начальное состояние сортировки <br> <strong>state</strong>: Состояние сортировки, жестко устанавливаемое снаружи <br> <strong>onChange</strong>: Колбэк на изменение сортировки |
| rowSelection | `{ initialState?: RowSelectionState; state?: RowSelectionState; enable?: boolean \| ((row: Row<TData>) => boolean); multiRow?: boolean; onChange?(state: RowSelectionState): void; }` | - | Параметры отвечают за возможность выбора строк <br> <strong>initialState</strong>: Начальное состояние выбора строк <br> <strong>state</strong>: Состояние выбора строк, жестко устанавливаемое снаружи <br> <strong>enable</strong>: Колбэк определяющий можно ли выбрать строку <br> <strong>multiRow</strong>: Мульти-выбор строк (включен по-умолчанию, когда включается выбор) <br> <strong>onChange</strong>: Колбэк на выбор строк |
| enableFuzzySearch | `boolean` | - | Включить нечеткий поиск |
| onRowClick | `RowClickHandler<TData>` | - | Колбэк клика по строке |
| className | `string` | - | CSS-класс |
| onRefresh | `() => void` | - | Колбек обновления данных |
| onDelete | `(selectionState: RowSelectionState, resetRowSelection: (defaultState?: boolean) => void) => void` | - | Колбек удаления выбранных |
| outline | `boolean` | - | Внешний бордер для тулбара и таблицы |
| columnFilters | `ReactNode` | - | Фильтры |
| dataFiltered | `boolean` | - |  |
| dataError | `boolean` | - |  |
| exportFileName | `string` | - | Название файла при экспорте CSV/XLSX |
| moreActions | `Action[]` | - | Элементы выпадающего списка кнопки с действиями |
| noDataState | `EmptyStateProps` | - | Экран при отстутствии данных |
| noResultsState | `EmptyStateProps` | - | Экран при отстутствии результатов поиска или фильтров |
| errorDataState | `EmptyStateProps` | - | Экран при ошибке запроса |
| suppressToolbar | `boolean` | - | Отключение тулбара |
| toolbarBefore | `ReactNode` | - | Дополнительный слот в `Toolbar` перед строкой поиска |
| toolbarAfter | `ReactNode` | - | Дополнительный слот в `Toolbar` после строки поиска |
| suppressPagination | `boolean` | - | Отключение пагинации |
| manualSorting | `boolean` | true |  |
| manualPagination | `boolean` | true |  |
| manualFiltering | `boolean` | true |  |
| getRowId | `(originalRow: TData, index: number, parent?: Row<TData>) => string` | - | Дополнительная функция используется для получения уникального идентификатора для любой заданной строки |
| scrollRef | `RefObject<HTMLElement>` | - | Ссылка на элемент, обозначающий самый конец прокручиваемого списка |
| scrollContainerRef | `RefObject<HTMLElement>` | - | Ссылка на контейнер, который скроллится |
| rowPinning | `Pick<RowPinningState, "top">` | - | Определение какие строки должны быть закреплены в таблице |
| items | `TData[]` | - | Данные для отрисовки |
| total | `number` | 10 | Общее кол-во строк |
| limit | `number` | 10 | Кол-во строк на страницу |
| offset | `number` | - | Смещение |
| search | `{ initialValue?: string; state: string; placeholder?: string; loading?: boolean; onChange(value: string): void; }` | 'Search...'<br> <strong>loading</strong>: Состояние загрузки в строке поиска <br> <strong>onChange</strong>: Колбэк на изменение данных в строке поиска | Параметры отвечают за глобальный поиск в таблице <br> <strong>initialState</strong>: Начальное состояние строки поиска <br> <strong>state</strong>: Состояние строки поиска, жестко устанавливаемое снаружи <br> <strong>placeholder</strong>: Placeholder строки поиска |
| pagination | `{ options?: number[]; optionsLabel?: string; }` | 'Rows volume' <br> | Параметры отвечают за пагинацию в таблице <br> <strong>options</strong>: Варианты в выпадающем селекторе для установки кол-ва строк на страницу<br> <strong>optionsLabel</strong>: Текст для селектора кол-ва строк на страницу |
## ServerTable.getRowActionsColumnDef
Вспомогательная функция для создания ячейки с дополнительными действиями у строки
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
| actionsGenerator* | `ActionsGenerator<TData>` | - | Действия для строки |
| pinned | `boolean` | - | Закрепление колонки справа в таблице |
## ServerTable.getStatusColumnDef
Вспомогательная функция для создания ячейки со статусом
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
| mapStatusToAppearance* | `MapStatusToAppearanceFnType` | - | Маппинг значений статуса на цвета |
| accessorKey* | `string` | - | Имя ключа соответствующее полю в data |
| enableSorting | `boolean` | - | Включение/выключение сортировки |
| renderDescription | `(cellValue: string) => string` | - | Функция для отрисовки текста, если не передана, то будет отрисован только индикатор статуса |
| size | `number` | - | Размер ячейки |
| header | `ColumnDefTemplate<HeaderContext<TData, unknown>> & (string \| ((ctx: HeaderContext<TData, unknown>) => string))` | - | Заголовок колонки |
| enableResizing | `boolean` | - | Включение/выключение ресайза колонки |
## exportToCSV
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
| columnDefinitions* | `ColumnDefinition<TData>[]` | - |  |
| data* | `TData[]` | - |  |
| fileName | `string` | Table |  |
## exportToXLSX
### Props
| name | type | default value | description |
|------|------|---------------|-------------|
| columnDefinitions* | `ColumnDefinition<TData>[]` | - |  |
| data* | `TData[]` | - |  |
| fileName | `string` | Table |  |


[//]: DOCUMENTATION_SECTION_END
